1 Summary 2 Component responsible 3 Architecture design 4 Installation manual 4.1 Development 4.2 Production 5 Test Cases 6 User Manual 6.1 API specification 6.2 HandBook

Summary

It is responsible for managing the deployment, execution and management of the different workflow instances. It will be multi-tenant leading to executing a workflow instance on behalf of one organisation by also taking care of the corresponding workflow and organisation data level. This component will expose:

• A graphical user interface for interacting with the different actors involved in the lifecycle of a workflow
• A REST API interface allowing programmatic access to the different types of functionalities offered.

The main functionalities are:

• Deploy/redeploy a workflow in the workflow-engine, instantiate it and execute it.
• Manage and follow the workflow instances, according to the workflow description in BPMN.
• Interact with manual tasks of the workflow.
• Manage the workflow engine environment.

Type of ownership	Extension & Adaptation
Original tool	FIWARE and Fed4FIRE project
Planned OS license	Apache License Version 2.0.
Reference community	Activiti community

Consist of

• Web UI of workflow Engine (Graphical User interface)
• Workflow Engine (core functionalities)

Depends on

• Process Data Mediator Engine
• IdM Marketplace

Component responsible

Developer	Email	Company
Roman Sosa Gonzalez	roman.sosa@atos.net	Atos
Joaquin Iranzo	Joaquin.iranzo@atos.net	Atos

Architecture design

Figure: General architecture for Workflow Engine

Installation manual

Development

Requirements

• Oracle JDK 1.7.x
• Tomcat 7.x
• Maven tool for building applications.

Installation

• Download source code https://xxxx.
• Components:
  • WorkflowEngineBpmnModelLite
  • WorkflowEngineManager
  • WorkflowEngineService
  • WorkflowEngineManagerServiceProxy
  • activiti-rest
  • activiti-webapp-rest2
  • activiti-webapp-explorer2
  • demo-app
• Create the necessary artifacs executing the following instruction for all of components:

  mvn install
  

• Copy the war file generated in the WorkflowEngineService, activiti-webapp-rest2 and emo-app modules into the webapps folder Tomcat.

  <modulePath>/target
  

Development environment

• Create the eclipse project executing the following instruction for all necessary components:

  mvn eclipse:eclipse
  

Production

Requirements

• OpenJDK 1.7.x
• MySql 5.5.x
• Tomcat 7.x
• Nginx

Installation

• Validate that the version of Java is the correct one, if not install the version

  #java -version
  java version "1.7.0_85"
  

• Install the requeriments

  sudo aptitude install mysql-server
  sudo aptitude install tomcat7
  sudo aptitude install nginx
  

• Configure the schema and user of the Activiti (the password of the root has been introduced during the MySql installation).

  mysql -h localhost -u root -p
  create database activiti_cloudsocket;
  create user cloudsocket@localhost identified by 'cloudsocket';
  grant all privileges on activiti_cloudsocket.* to cloudsocket@localhost;
  

• Configure the modules of Tomcat (if you want to change the default password). Modify the file "<activiti-webapp-rest2>/WEB-INF/classes/db.properties" and "<activiti-webapp-explorer2>/WEB-INF/classes/db.properties" in order to introduce the new password.

  db=mysql
  jdbc.driver=com.mysql.jdbc.Driver
  jdbc.url=jdbc:mysql://localhost:3306/activiti_cloudsocket
  jdbc.username=cloudsocket
  jdbc.password=cloudsocket
  

• Configure the Nginx to redirect the 80 --> 8080. Modify the file (/etc/nginx/sites-available)

  server {
      listen   0.0.0.0:80;
      server_name localhost 134.60.64.132;
  
      client_max_body_size 4G;
  
      access_log /var/log/nginx/workflow_Engine.access.log;
      error_log /var/log/nginx/workflow_Engine.error.log;
  
      location /demo-app-1.0/ {
          # an HTTP header important enough to have its own Wikipedia entry:
          #   http://en.wikipedia.org/wiki/X-Forwarded-For
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  
          # enable this if and only if you use HTTPS, this helps Rack
          # set the proper protocol for doing redirects:
          # proxy_set_header X-Forwarded-Proto https;
  
          # pass the Host: header from the client right along so redirects
          # can be set properly within the Rack application
          prost $http_host;
  
          # we don't want nginx trying to do something clever with
          # redirects, we set the Host: header above already.
          proxy_redirect off;
  
          proxy_pass http://localhost:8080/demo-app-1.0/;
      }
      
      location /activiti-webapp-rest2/ {
          # an HTTP header important enough to have its own Wikipedia entry:
          #   http://en.wikipedia.org/wiki/X-Forwarded-For
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  
          # enable this if and only if you use HTTPS, this helps Rack
          # set the proper protocol for doing redirects:
          # proxy_set_header X-Forwarded-Proto https;
  
          # pass the Host: header from the client right along so redirects
          # can be set properly within the Rack application
          proxy_set_header Host $http_host;
  
          # we don't want nginx trying to do something clever with
          # redirects, we set the Host: header above already.
          proxy_redirect off;
  
          proxy_pass http://localhost:8080/activiti-webapp-rest2/;
      }
  
      location /activiti-webapp-explorer2/ {
          # an HTTP header important enough to have its own Wikipedia entry:
          #   http://en.wikipedia.org/wiki/X-Forwarded-For
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  
          # enable this if and only if you use HTTPS, this helps Rack
          # set the proper protocol for doing redirects:
          # proxy_set_header X-Forwarded-Proto https;
  
          # pass the Host: header from the client right along so redirects
          # can be set properly within the Rack application
          proxy_set_header Host $http_host;
  
          # we don't want nginx trying to do something clever with
          # redirects, we set the Host: header above already.
          proxy_redirect off;
  
          proxy_pass http://localhost:8080/activiti-webapp-explorer2/;
      }
  
  
  }
  

• Locate the war artifacts at the server:

  - WorkflowEngineService
  - activiti-webapp-rest2
  - activiti-webapp-explorer2
  - demo-app
  

• Copy the war to the the tomcat folder (/var/lib/tomcat7/webapps)

  sudo cp * /var/lib/tomcat7/webapps
  

• Test the installation. Open a Navigator and test the following URLs:

  http://134.60.64.132/demo-app-1.0/services/
  http://134.60.64.132/activiti-webapp-explorer2/
  http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments (basic authentication:kermit/kermit)
  

Test Cases

To execute the unit tests, we need to install the tool curl http://curl.haxx.se/ Optional: if you want to see the formatted response, the python library can be used. If not, you only need to remove this part: “| python -mjson.tool” of the command.

• Create a new deployement:

It is needed to execute the following command:

curl -X POST -F "file=@testCloudsocket.bpmn20.xml" -F "tenantId=ATOS" -F "endPointServiceList={\"workFlowId\":\"wf1\",\"endPointServices\":[{\"serviceId\":\"http://localhost:8080/demo-app-1.0/services/cardDesigner?wsdl\",\"serviceTaskId\":\"\",\"type\":\"WS\",\"ip\":\"127.0.0.1:8080\"},{\"serviceId\":\"http://localhost:8080/demo-app-1.0/services/email?wsdl\",\"serviceTaskId\":\"\",\"type\":\"WS\",\"ip\":\"127.0.0.1:8080\"}]}" --user kermit:kermit -H "content-type: multipart/form-data" http:// 134.60.64.132/activiti-webapp-rest2/service/repository/deployments | python -mjson.tool

Where the attributes are:

• File is the bpm2.0 file (testCloudsocket.bpmn20.xml)
• TenantId is the tenant of the organization (for the moment it is not used).
• endPointServiceList is the list of the actual IP for the two services.

  Success response
  {
      "category": null,
      "deploymentTime": "2015-10-27T22:00:45.161Z",
      "id": "40",
      "name": "testCloudsocket.bpmn20.xml",
      "tenantId": "ATOS",
      "url": "http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40"
  }
  

• Detail of the deployement

  curl --user kermit:kermit  http:// 134.60.64.132/activiti-webapp-rest2/service/repository/deployments/{deploymentId} | python -mjson.tool
  in our case deploymentId is 40:
  curl --user kermit:kermit http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40 | python -mjson.tool
  

The description appears for your deployment.

{
    "category": null,
    "deploymentTime": "2015-10-30T15:21:42.711+01:00",
    "id": "40",
    "name": "testCloudsocket.bpmn20.xml",
    "tenantId": "ATOS",
    "url": "http://127.0.0.1:8080/activiti-rest/service/repository/deployments/40"
}

• List of resources associated

  curl --user kermit:kermit http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/{deploymentId}/resources | python -mjson.tool
  in our case deploymentId is 40:
  curl --user kermit:kermit http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resources | python -mjson.tool
  

List of resources appears.

[
    {
        "contentUrl": "http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resourcedata/testCloudsocket.bpmn20.xml",
        "id": "testCloudsocket.bpmn20.xml",
        "mediaType": "text/xml",
        "type": "processDefinition",
        "url": "http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resources/testCloudsocket.bpmn20.xml"
    },
    {
        "contentUrl": "http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resourcedata/testCloudsocket.testCloudsocket.png",
        "id": "testCloudsocket.testCloudsocket.png",
        "mediaType": "image/png",
        "type": "resource",
        "url": "http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resources/testCloudsocket.testCloudsocket.png"
    }
]

• Get the associated resource

  curl --user kermit:kermit http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/{deploymentId}/resourcedata/testCloudsocket.bpmn20.xml
  

In our case deploymentId is the id 40:

curl --user kermit:kermit http://134.60.64.132/activiti-webapp-rest2/service/repository/deployments/40/resourcedata/testCloudsocket.bpmn20.xml

The BPMN file associated to our deployment:

<?xml version='1.0' encoding='UTF-8'?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:activiti="http://activiti.org/bpmn" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC" xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI" typeLanguage="http://www.w3.org/2001/XMLSchema" expressionLanguage="http://www.w3.org/1999/XPath" targetNamespace="http://www.activiti.org/processdef">
  <import namespace="http://demo.seiplab.atosresearch.eu/" location="http://http://127.0.0.1:8080/demo-app-1.0/services/cardDesigner?wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>
  <import namespace="http://demo.seiplab.atosresearch.eu/" location="http://http://127.0.0.1:8080/demo-app-1.0/services/email?wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>
  <process id="testCloudsocket" name="testCloudsocket" isExecutable="true">
    <userTask id="sid-9956FEED-377C-4C6D-81F5-1DF14EE36D56" name="test" activiti:candidateGroups="sales"/>
    <startEvent id="sid-AD365612-18DE-48F1-971F-944E51AB8804"/>
    <endEvent id="sid-F9B53F7F-5822-4653-BA91-CA88B3A026D3"/>
    <sequenceFlow id="sid-685E0C22-D2AD-4DF4-96C6-A435792C214A" sourceRef="sid-AD365612-18DE-48F1-971F-944E51AB8804" targetRef="sid-9956FEED-377C-4C6D-81F5-1DF14EE36D56"/>
    <sequenceFlow id="sid-541CE92A-8C33-4041-9359-693F38333D2F" sourceRef="sid-9956FEED-377C-4C6D-81F5-1DF14EE36D56" targetRef="sid-F9B53F7F-5822-4653-BA91-CA88B3A026D3"/>
  </process>
  <bpmndi:BPMNDiagram id="BPMNDiagram_testCloudsocket">
    <bpmndi:BPMNPlane bpmnElement="testCloudsocket" id="BPMNPlane_testCloudsocket">
      <bpmndi:BPMNShape bpmnElement="sid-9956FEED-377C-4C6D-81F5-1DF14EE36D56" id="BPMNShape_sid-9956FEED-377C-4C6D-81F5-1DF14EE36D56">
        <omgdc:Bounds height="80.0" width="100.0" x="315.0" y="163.0"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape bpmnElement="sid-AD365612-18DE-48F1-971F-944E51AB8804" id="BPMNShape_sid-AD365612-18DE-48F1-971F-944E51AB8804">
        <omgdc:Bounds height="30.0" width="30.0" x="136.45001220703125" y="184.0"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape bpmnElement="sid-F9B53F7F-5822-4653-BA91-CA88B3A026D3" id="BPMNShape_sid-F9B53F7F-5822-4653-BA91-CA88B3A026D3">
        <omgdc:Bounds height="28.0" width="28.0" x="575.4500122070312" y="189.0"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNEdge bpmnElement="sid-541CE92A-8C33-4041-9359-693F38333D2F" id="BPMNEdge_sid-541CE92A-8C33-4041-9359-693F38333D2F">
        <omgdi:waypoint x="415.0" y="203.0"/>
        <omgdi:waypoint x="575.4500122070312" y="203.0"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge bpmnElement="sid-685E0C22-D2AD-4DF4-96C6-A435792C214A" id="BPMNEdge_sid-685E0C22-D2AD-4DF4-96C6-A435792C214A">
        <omgdi:waypoint x="166.44738152787627" y="199.2809153861509"/>
        <omgdi:waypoint x="315.0" y="202.06345112885748"/>
      </bpmndi:BPMNEdge>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
</definitions>

• Delete the deploment

  curl -X DELETE --user kermit:kermit http://127.0.0.1:8080/activiti-rest/service/repository/deployments/40
  

User Manual

API specification

We have extended the Activiti API, so you can find more information in the following link Activiti REST API

Create a new deployment:

POST repository/deployments

The request body should contain data of type multipart/form-data. There should be exactly one file in the request, any additional files will be ignored. The deployment name is the name of the file-field passed in. If multiple resources need to be deployed in a single deployment, compress the resources in a zip and make sure the file-name ends with .bar or .zip.

Two additional parameters (form-field) can be passed in the request body:

• tenantId: it is the id of the tenant that will be associated to the deploy business process.
• endPointServiceList: It is the list of the actual URL (IP/host_name and the port) of the associated services. The parameter has to have the following structure:

EndPointServiceBundle: contain all the necessary information to modify the bpmn with the actual service IPs

• workFlowId(literal): Identify the workflowId
• endPointServices (EndPointServices[]): list of the actual IPs of services, it is described by the EndPointServices entity.

EndPointServices: Include the details to identify the services and contains the real IP.

• serviceId (literal): identification of the services.
• type (literal): Only accepted two values: WS (Web services) and REST.
• serviceTaskId (literal): Indicate the identifier of the service task, associated to this serviceId. It is optional since there are some situation where the description of the services are not associated directly to the service task.
• Ip (literal): It indicates the IP/Name of the host plus the port, following the pattern <ip/host_name>:<port>. If the port is 80 o 443 it is not necessary to include them in this attribute.

Example of the json file:

{
   "workFlowId":"wf1",
   "endPointServices":[
      {
         "serviceId":"http://localhost:8080/demo-app-1.0/services/cardDesigner?wsdl",
         "serviceTaskId":"",
         "type":"WS",
         "ip":"127.0.0.1:8080"
      },
      {
         "serviceId":"http://localhost:8080/demo-app-1.0/services/email?wsdl",
         "serviceTaskId":"",
         "type":"WS",
         "ip":"127.0.0.1:8080"
     }
   ]
}

Note: Change the ip attribute with the available Web Service definition (running WSDL description), if not the WorkflowEngine doesn’t allow to deploy the BPMN file. Response codes:

*201    Indicates the deployment was created.
*400    Indicates there was no content present in the request body or the content mime-type is not supported for deployment. The status-description contains additional information.

Success response body:

{
    "category": null,
    "deploymentTime": "2015-10-30T15:21:42.711+01:00",
    "id": "40",
    "name": "withEmail.bpmn20.xml",
    "tenantId": "ATOS",
    "url": "http://127.0.0.1:8080/activiti-rest/service/repository/deployments/40"
}

HandBook